home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_tables.h.z / apr_tables.h
C/C++ Source or Header  |  2002-07-08  |  16KB  |  434 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_TABLES_H
  56. #define APR_TABLES_H
  57.  
  58. #include "apr.h"
  59. #include "apr_pools.h"
  60.  
  61. #if APR_HAVE_STDARG_H
  62. #include <stdarg.h>     /* for va_list */
  63. #endif
  64.  
  65. #ifdef __cplusplus
  66. extern "C" {
  67. #endif /* __cplusplus */
  68.  
  69. /*
  70.  * Define the structures used by the APR general-purpose library.
  71.  */
  72.  
  73. /**
  74.  * @file apr_tables.h
  75.  * @brief APR Table library
  76.  */
  77. /**
  78.  * @defgroup APR_Table Table routines
  79.  * @ingroup APR
  80.  *
  81.  * Memory allocation stuff, like pools, arrays, and tables.  Pools
  82.  * and tables are opaque structures to applications, but arrays are
  83.  * published.
  84.  * @{
  85.  */
  86. /** the table abstract data type */
  87. typedef struct apr_table_t apr_table_t;
  88.  
  89. /** An opaque array type */
  90. typedef struct apr_array_header_t apr_array_header_t;
  91.  
  92. struct apr_array_header_t {
  93.     /** The pool the array is allocated out of */
  94.     apr_pool_t *pool;
  95.     /** The amount of memory allocated for each element of the array */
  96.     int elt_size;
  97.     /** The number of active elements in the array */
  98.     int nelts;
  99.     /** The number of elements allocated in the array */
  100.     int nalloc;
  101.     /** The elements in the array */
  102.     char *elts;
  103. };
  104.  
  105. /** The opaque string-content table type */
  106. struct apr_table_t {
  107.     /* This has to be first to promote backwards compatibility with
  108.      * older modules which cast a apr_table_t * to an apr_array_header_t *...
  109.      * they should use the table_elts() function for most of the
  110.      * cases they do this for.
  111.      */
  112.     /** The underlying array for the table */
  113.     apr_array_header_t a;
  114. #ifdef MAKE_TABLE_PROFILE
  115.     /** Who created the array. */
  116.     void *creator;
  117. #endif
  118. };
  119.  
  120. /**
  121.  * The (opaque) structure for string-content tables.
  122.  */
  123. typedef struct apr_table_entry_t apr_table_entry_t;
  124.  
  125. /** The type for each entry in a string-content table */
  126. struct apr_table_entry_t {
  127.     /** The key for the current table entry */
  128.     char *key;          /* maybe NULL in future;
  129.                          * check when iterating thru table_elts
  130.                          */
  131.     /** The value for the current table entry */
  132.     char *val;
  133.  
  134.     /** A checksum for the key, for use by the apr_table internals */
  135.     apr_uint32_t key_checksum;
  136. };
  137.  
  138. /**
  139.  * Get the elements from a table
  140.  * @param t The table
  141.  * @return An array containing the contents of the table
  142.  */
  143. #define apr_table_elts(t) ((const apr_array_header_t *)(t))
  144.  
  145. /**
  146.  * Determine if the table is empty
  147.  * @param t The table to check
  148.  * @return True if empty, False otherwise
  149.  */
  150. #define apr_is_empty_table(t) (((t) == NULL) \
  151.                                || (((apr_array_header_t *)(t))->nelts == 0))
  152.  
  153. /**
  154.  * Create an array
  155.  * @param p The pool to allocate the memory out of
  156.  * @param nelts the number of elements in the initial array
  157.  * @param elt_size The size of each element in the array.
  158.  * @return The new array
  159.  */
  160. APR_DECLARE(apr_array_header_t *) apr_array_make(apr_pool_t *p,
  161.                                                  int nelts, int elt_size);
  162.  
  163. /**
  164.  * Add a new element to an array
  165.  * @param arr The array to add an element to.
  166.  * @return Location for the new element in the array.
  167.  * @remark If there are no free spots in the array, then this function will
  168.  *         allocate new space for the new element.
  169.  */
  170. APR_DECLARE(void *) apr_array_push(apr_array_header_t *arr);
  171.  
  172. /**
  173.  * Concatenate two arrays together
  174.  * @param dst The destination array, and the one to go first in the combined 
  175.  *            array
  176.  * @param src The source array to add to the destination array
  177.  */
  178. APR_DECLARE(void) apr_array_cat(apr_array_header_t *dst,
  179.                     const apr_array_header_t *src);
  180.  
  181. /**
  182.  * Copy the entire array
  183.  * @param p The pool to allocate the copy of the array out of
  184.  * @param arr The array to copy
  185.  * @return An exact copy of the array passed in
  186.  * @remark The alternate apr_array_copy_hdr copies only the header, and arranges 
  187.  *         for the elements to be copied if (and only if) the code subsequently
  188.  *         does a push or arraycat.
  189.  */
  190. APR_DECLARE(apr_array_header_t *) apr_array_copy(apr_pool_t *p,
  191.                                       const apr_array_header_t *arr);
  192. /**
  193.  * Copy the headers of the array, and arrange for the elements to be copied if
  194.  * and only if the code subsequently does a push or arraycat.
  195.  * @param p The pool to allocate the copy of the array out of
  196.  * @param arr The array to copy
  197.  * @return An exact copy of the array passed in
  198.  * @remark The alternate apr_array_copy copies the *entire* array.
  199.  */
  200. APR_DECLARE(apr_array_header_t *) apr_array_copy_hdr(apr_pool_t *p,
  201.                                       const apr_array_header_t *arr);
  202.  
  203. /**
  204.  * Append one array to the end of another, creating a new array in the process.
  205.  * @param p The pool to allocate the new array out of
  206.  * @param first The array to put first in the new array.
  207.  * @param second The array to put second in the new array.
  208.  * @param return A new array containing the data from the two arrays passed in.
  209. */
  210. APR_DECLARE(apr_array_header_t *) apr_array_append(apr_pool_t *p,
  211.                                       const apr_array_header_t *first,
  212.                                       const apr_array_header_t *second);
  213.  
  214. /**
  215.  * Generates a new string from the apr_pool_t containing the concatenated 
  216.  * sequence of substrings referenced as elements within the array.  The string 
  217.  * will be empty if all substrings are empty or null, or if there are no 
  218.  * elements in the array.  If sep is non-NUL, it will be inserted between 
  219.  * elements as a separator.
  220.  * @param p The pool to allocate the string out of
  221.  * @param arr The array to generate the string from
  222.  * @param sep The separator to use
  223.  * @return A string containing all of the data in the array.
  224.  */
  225. APR_DECLARE(char *) apr_array_pstrcat(apr_pool_t *p,
  226.                       const apr_array_header_t *arr,
  227.                       const char sep);
  228.  
  229. /**
  230.  * Make a new table
  231.  * @param p The pool to allocate the pool out of
  232.  * @param nelts The number of elements in the initial table.
  233.  * @return The new table.
  234.  * @warning This table can only store text data
  235.  */
  236. APR_DECLARE(apr_table_t *) apr_table_make(apr_pool_t *p, int nelts);
  237.  
  238. /**
  239.  * Create a new table and copy another table into it
  240.  * @param p The pool to allocate the new table out of
  241.  * @param t The table to copy
  242.  * @return A copy of the table passed in
  243.  */
  244. APR_DECLARE(apr_table_t *) apr_table_copy(apr_pool_t *p,
  245.                                           const apr_table_t *t);
  246.  
  247. /**
  248.  * Delete all of the elements from a table
  249.  * @param t The table to clear
  250.  */
  251. APR_DECLARE(void) apr_table_clear(apr_table_t *t);
  252.  
  253. /**
  254.  * Get the value associated with a given key from the table.  After this call,
  255.  * The data is still in the table
  256.  * @param t The table to search for the key
  257.  * @param key The key to search for
  258.  * @return The value associated with the key
  259.  */
  260. APR_DECLARE(const char *) apr_table_get(const apr_table_t *t, const char *key);
  261.  
  262. /**
  263.  * Add a key/value pair to a table, if another element already exists with the
  264.  * same key, this will over-write the old data.
  265.  * @param t The table to add the data to.
  266.  * @param key The key fo use
  267.  * @param val The value to add
  268.  * @remark When adding data, this function makes a copy of both the key and the
  269.  *         value.
  270.  */
  271. APR_DECLARE(void) apr_table_set(apr_table_t *t, const char *key,
  272.                                 const char *val);
  273.  
  274. /**
  275.  * Add a key/value pair to a table, if another element already exists with the
  276.  * same key, this will over-write the old data.
  277.  * @param t The table to add the data to.
  278.  * @param key The key fo use
  279.  * @param val The value to add
  280.  * @warning When adding data, this function does not make a copy of the key or 
  281.  *          the value, so care should be taken to ensure that the values will 
  282.  *          not change after they have been added..
  283.  */
  284. APR_DECLARE(void) apr_table_setn(apr_table_t *t, const char *key,
  285.                                  const char *val);
  286.  
  287. /**
  288.  * Remove data from the table
  289.  * @param t The table to remove data from
  290.  * @param key The key of the data being removed
  291.  */
  292. APR_DECLARE(void) apr_table_unset(apr_table_t *t, const char *key);
  293.  
  294. /**
  295.  * Add data to a table by merging the value with data that has already been 
  296.  * stored
  297.  * @param t The table to search for the data
  298.  * @param key The key to merge data for
  299.  * @param val The data to add
  300.  * @remark If the key is not found, then this function acts like apr_table_add
  301.  */
  302. APR_DECLARE(void) apr_table_merge(apr_table_t *t, const char *key,
  303.                                   const char *val);
  304.  
  305. /**
  306.  * Add data to a table by merging the value with data that has already been 
  307.  * stored
  308.  * @param t The table to search for the data
  309.  * @param key The key to merge data for
  310.  * @param val The data to add
  311.  * @remark If the key is not found, then this function acts like apr_table_addn
  312.  */
  313. APR_DECLARE(void) apr_table_mergen(apr_table_t *t, const char *key,
  314.                                    const char *val);
  315.  
  316. /**
  317.  * Add data to a table, regardless of whether there is another element with the
  318.  * same key.
  319.  * @param t The table to add to
  320.  * @param key The key to use
  321.  * @param val The value to add.
  322.  * @remark When adding data, this function makes a copy of both the key and the
  323.  *         value.
  324.  */
  325. APR_DECLARE(void) apr_table_add(apr_table_t *t, const char *key,
  326.                                 const char *val);
  327.  
  328. /**
  329.  * Add data to a table, regardless of whether there is another element with the
  330.  * same key.
  331.  * @param t The table to add to
  332.  * @param key The key to use
  333.  * @param val The value to add.
  334.  * @remark When adding data, this function does not make a copy of the key or the
  335.  *         value, so care should be taken to ensure that the values will not 
  336.  *         change after they have been added..
  337.  */
  338. APR_DECLARE(void) apr_table_addn(apr_table_t *t, const char *key,
  339.                                  const char *val);
  340.  
  341. /**
  342.  * Merge two tables into one new table
  343.  * @param p The pool to use for the new table
  344.  * @param overlay The first table to put in the new table
  345.  * @param base The table to add at the end of the new table
  346.  * @return A new table containing all of the data from the two passed in
  347.  */
  348. APR_DECLARE(apr_table_t *) apr_table_overlay(apr_pool_t *p,
  349.                                              const apr_table_t *overlay,
  350.                                              const apr_table_t *base);
  351.  
  352. /** 
  353.  * Iterate over a table running the provided function once for every
  354.  * element in the table.  If there is data passed in as a vararg, then the 
  355.  * function is only run on those elements whose key matches something in 
  356.  * the vararg.  If the vararg is NULL, then every element is run through the
  357.  * function.  Iteration continues while the function returns non-zero.
  358.  * @param comp The function to run
  359.  * @param rec The data to pass as the first argument to the function
  360.  * @param t The table to iterate over
  361.  * @param ... The vararg.  If this is NULL, then all elements in the table are
  362.  *            run through the function, otherwise only those whose key matches
  363.  *            are run.
  364.  */
  365. APR_DECLARE_NONSTD(void) apr_table_do(int (*comp)(void *, const char *, const char *),
  366.                              void *rec, const apr_table_t *t, ...);
  367.  
  368. /** 
  369.  * Iterate over a table running the provided function once for every
  370.  * element in the table.  If there is data passed in as a vararg, then the 
  371.  * function is only run on those element's whose key matches something in 
  372.  * the vararg.  If the vararg is NULL, then every element is run through the
  373.  * function.  Iteration continues while the function returns non-zero.
  374.  * @param comp The function to run
  375.  * @param rec The data to pass as the first argument to the function
  376.  * @param t The table to iterate over
  377.  * @param vp The vararg table.  If this is NULL, then all elements in the 
  378.  *                table are run through the function, otherwise only those 
  379.  *                whose key matches are run.
  380.  */
  381. APR_DECLARE(void) apr_table_vdo(int (*comp)(void *, const char *, const char *),
  382.                                 void *rec, const apr_table_t *t, va_list);
  383.  
  384. /** flag for overlap to use apr_table_setn */
  385. #define APR_OVERLAP_TABLES_SET   (0)
  386. /** flag for overlap to use apr_table_mergen */
  387. #define APR_OVERLAP_TABLES_MERGE (1)
  388. /**
  389.  * For each element in table b, either use setn or mergen to add the data
  390.  * to table a.  Which method is used is determined by the flags passed in.
  391.  * @param a The table to add the data to.
  392.  * @param b The table to iterate over, adding its data to table a
  393.  * @param flags How to add the table to table a.  One of:
  394.  *          APR_OVERLAP_TABLES_SET        Use apr_table_setn
  395.  *          APR_OVERLAP_TABLES_MERGE      Use apr_table_mergen
  396.  * @remark  This function is highly optimized, and uses less memory and CPU cycles
  397.  *          than a function that just loops through table b calling other functions.
  398.  */
  399. /**
  400.  *<PRE>
  401.  * Conceptually, apr_table_overlap does this:
  402.  *
  403.  *  apr_array_header_t *barr = apr_table_elts(b);
  404.  *  apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
  405.  *  int i;
  406.  *
  407.  *  for (i = 0; i < barr->nelts; ++i) {
  408.  *      if (flags & APR_OVERLAP_TABLES_MERGE) {
  409.  *          apr_table_mergen(a, belt[i].key, belt[i].val);
  410.  *      }
  411.  *      else {
  412.  *          apr_table_setn(a, belt[i].key, belt[i].val);
  413.  *      }
  414.  *  }
  415.  *
  416.  *  Except that it is more efficient (less space and cpu-time) especially
  417.  *  when b has many elements.
  418.  *
  419.  *  Notice the assumptions on the keys and values in b -- they must be
  420.  *  in an ancestor of a's pool.  In practice b and a are usually from
  421.  *  the same pool.
  422.  * </PRE>
  423.  */
  424.  
  425. APR_DECLARE(void) apr_table_overlap(apr_table_t *a, const apr_table_t *b,
  426.                                      unsigned flags);
  427.  
  428. /** @} */
  429. #ifdef __cplusplus
  430. }
  431. #endif
  432.  
  433. #endif    /* ! APR_TABLES_H */
  434.